Generated code - Using the entity classes, SelfServicing

Preface

When you generate code and you opt for the TwoClasses preset in combination of the SelfServicing template group you'll notice that there are actually two classes (hence the two class scenario) per entity which are used in a 'base class' - 'derived class' way. (When you use the General preset, there is just one class, EntityNameEntity.cs/vb, which contains the same functionality as the EntityNameEntityBase.cs/vb class generated in the TwoClasses situation). This section describes the TwoClasses situation and how to use the base class and derived class for every entity in your code, though the topics addressed can easily be applied to the generated code produced when using the General preset as well.

All entity classes derive from a central, generated base class called CommonEntityBase. This class is the base class for all generated entity classes and it derives from the class EntityBase, which is located in the ORMSupportClasses assembly. The CommonEntityBase class is usable to add code (via a partial class or using the user code regions) to all generated entities without having to generate / add that code to all entity classes separately.

The section below is the same for entities in an inheritance hierarchy as for entities not in an inheritance hierarchy, unless stated otherwise.

Two classes

The base class, generally named EntityNameEntityBase.cs/vb, for example OrderEntityBase.cs, is the class containing all the logic and the implementations of various methods defined in the EntityBase class in the ORMSupportClasses namespace. This base class derives from the central generated base class CommonEntityBase. The other class, EntityNameEntity.cs/vb, for example OrderEntity.cs, is the class you work with in your code; in other words, the class you use as the type to instantiate entity objects. When you're using .NET 1.x, this is also the class where you will add custom code to the entity classes, for example extra properties. When you're using .NET 2.0, it's recommended to use partial classes instead, a new feature of .NET 2.0. You can create a partial class for either one of the generated entity classes. It's however recommended that if you're using .NET 2.0 and you're starting a new project, you use the General preset and partial classes as that will likely give you less generated code.

Note:

The TwoClasses presets will overwrite the derived entity classes if these files exist, which is a change from v1.0.2005.1 and earlier versions, which didn't overwrite the derived entity classes. The contained user code regions will of course be preserved.

Adding your own code to the generated classes for details on modifying the generated code.

Instantiating an existing entity

As described in the concepts, an entity is a semantic name for a group of existing data. An entity has a definition, the entity definition, which is formulated in a database table or view and, when you added that entity definition to your project, also in code, namely in the EntityNameEntityBase.cs/vb class. To load the entity's data from the persistent storage, we use the generated class related to this entity's definition, and create an instance of that class and order it to load the data of the particular entity. As an example we're loading the entity identified with the customerID "CHOPS" into an object.

Using the primary key value

One way to instantiate the entity in an object is by passing all primary key values to the constructor of the entity class to use:


This will load the entity with the primary key value of "CHOPS" into the object named customer, directly from the persistent storage. LLBLGen Pro doesn't use an in-memory cache of objects, to prevent concurrency issues among multiple threads in multiple appdomains (which is the case when you run a client on two or more machines, when you have a web-farm or when your business logic is stored on multiple machines), though does provide a way to implement uniquing or caching through the Context object. See Using the context, SelfServicing for more details about the context.

Another, less compact way is to use an empty entity object and to fetch it by calling its fetch method:

Using a related entity

Another way to instantiate this same entity is via a related entity. Let's load the order with ID 10254, which is an order of customer "CHOPS", and via that order, get an instance of the entity "CHOPS".


LLBLGen Pro automatically creates properties to retrieve related entities or collections of related entities, using an instance of a given entity. It doesn't matter what type the relation between the two entities has: 1:n, m:1, 1:1 or m:n. In this case, Customer and Order have an 1:n relationship (one customer can have multiple orders) from the Customer's point of view and a m:1 relationship (one Order can have just one customer) from the Order's point of view.

A single entity property, which order.Customer is, uses the method GetSingleFieldMappedOnRelation() to actually retrieve the entity. You can use that method too, instead of the property:


If Customer is in an inheritance hierarchy, the fetch is polymorphic. This means that if the order entity, in this case order 10254, has a reference to a derived type of Customer, for example GoldCustomer, the entity returned will be of type GoldCustomer. See also Polymorphic fetches below.

Load on demand/Lazy loading
Once loaded, the entity is not loaded again, if you access the property again. This is called load on demand or lazy loading: the load action of the related entity (in our example 'customer') is done when you ask for it, not when the referencing entity (in our example 'order') is loaded. You can set a flag which makes the code load the related entity each time you access the property: AlwaysFetchFieldMappedOnRelation. In our example of Order and Customer, OrderEntity has a property called AlwaysFetchCustomer and CustomerEntity has a property called AlwaysFetchOrders. Default for these properties is 'false'. Setting these properties to true, will assure that the related entity is reloaded from the database each time you access the property. This can be handy if you want to stay up to date with the related entity state in the database. It can degrade performance, so use the property with care.

Another way to force loading of a related entity or collection is by specifying true for the forceFetch parameter in the GetSingleFieldMappedOnRelation call, or when the property contains a collection, GetMultiFieldMappedOnRelation call. Forcing a fetch has a difference with AlwaysFetchFieldMappedOnRelation in that a forced fetch will clear the collection first, while AlwaysFetchFieldMappedOnRelation does not. A forced fetch will thus remove new entities added to the collection from that collection as these are not yet stored in the database.

If you use a prefetch path to read a Customer and its related Order entities from the database, the Orders will not be re-loaded if you access the property after the fetch. A prefetch path which loads related entities makes sure that lazy loading will not undo the work the prefetch path already performed.

When the related entity is not found in the database, for example Customer has an optional relation (weak relation) with Address using Customer.VisitingAddressID - Address.AddressID and myCustomer.VisitingAddress is accessed and myCustomer doesn't have a related visiting address entity, by default the generated code will return a new, empty entity, in this case a new AddressEntity instance. You can then test the Fields.State value of the returned entity, if it is a new entity or a fetched entity (by comparing the Fields.State property with EntityState.New for a new entity or EntityState.Fetched for a fetched entity).

This can be cumbersome in some situations. You can tell the entity to return null (C#) or Nothing (VB.NET) instead of a new entity if the entity is not found by setting the property FieldMappedOnRelationReturnNewIfNotFound to false. In our example of the Customer and its optional VisitingAddress field, mapped on the relation Customer.VisitingAddressID - Address.AddressID, Customer will have a property VisitingAddressReturnNewIfNotFound. Setting this property to false will make myCustomer.VisitingAddress return null (C#) or Nothing (VB.NET) if the related Address entity is not found for myCustomer. By default these flags are set to true, to avoid code breakage with existing code already in production. You can change this default in the LLBLGen Pro designer: in the preferences and project properties, change the preference (which is inherited by a new project) or project property (if you're working on an existing project, be sure you set the property on the project as well) LazyLoadingWithoutResultReturnsNew to false and re-generate your code. The code generator will now generate 'false' / False' for all FieldMappedOnRelationReturnNewIfNotFound flags in all entities which will make sure that if an entity doesn't exist, null / Nothing is returned instead of a new entity.

Note:

Be aware that some code can trigger lazy loading while you didn't intent to. Consider Customer and Order which have an 1:n relation (and Order and Customer have a m:1 relation). The following code triggers the fetch of all orders for the myCustomer instance, while that wasn't the intention: myCustomer.Orders.Add(myOrder); while this code: myOrder.Customer = myCustomer; does the same thing, as LLBLGen Pro keeps both sides of a relation in sync, however this line of code doesn't trigger lazy loading.

Using a unique constraint's value

We just used the primary key value for the entity "CHOPS", which is the unique identifying attribute for the entity "CHOPS", to be exact. The customer entity also has a unique constraint defined on its field 'CompanyName', which therefore also is a unique identifying attribute for the same entity. We can use that field to load the same entity. Because a unique constraint which has the same types of fields as the primary key would result in the same constructor header and that would not be compilable, fetching the entity using a unique constraint is done via two steps: first create an empty entity object, then fetch the entity data using a method call. Because an entity can have more than one unique constraint, these have the fields in the unique constraint in the methodnames. In this case, the entity Customer has a unique constraint with one field, CompanyName, which is utilized by method FetchUsingUCCompanyName(companyName):

Using a prefetch path

An easy way to instantiate an entity can be by using a Prefetch Path, to read related entities together with the entity or entities to fetch. See for more information about Prefetch Paths and how to use them: Prefetch Paths.

Using a collection class

Another way to instantiate an entity is by creating a collection class with one or more entities of the same entity definition (entity type, like Customer) using the EntityCollection classes or via a related entity which has a 1:n relation with the entity to instantiate. For an example, please see Tutorials and Examples: How Do I? - Read all entities into a collection.

Using a Context object

If you want to get a reference to an entity object already in memory, you can use a Context object, if that object was added to that particular Context object. The example below retrieves a reference to the customer object with PK "CHOPS", if that entity was previously loaded into an entity object which was added to that Context object. If the entity object isn't in the Context object, a new entity object is returned. An example usage is shown below.

Creating a new / modifying an existing entity

This section discusses how to create a new entity and save it to the database and how to modify an existing entity and persist the changes.

Creating an entity

Loading an entity is nice, but it has to be created before it can be loaded. To create a new entity, simply instantiate an empty entity object, in this case a new Customer:


To create the entity in the persistent storage, two things have to be done: 1) the entity's data (which is new) has to be stored in the new entity object and 2) the entity data has to be persisted / saved in the persistent storage. Let's add the customer Foo Inc. to the database, do the following:


Region isn't filled in, which is fine, it can be NULL, and will therefore also end up as NULL in the database. This will save the data directly to the persistent storage (database) and the entity is immediately available for other threads / appdomains targeting the same database. The entity object customer itself is marked 'out of sync', which means that the entity's data is refetched from the database when you try to read one of the object's field's value. This way, you can immediately refetch values which are set inside the database, for example default values for columns. The code is aware of sequences / identity columns and will automatically set the value for an identity / sequence column right after the Save() method returns, thus is available in the next statement after a call to Save(). If you're using a database which uses sequences, like Oracle or Firebird, be sure to define the field which should be used with a sequence as identity in the entity editor.

Because the entity saved is new (customer.IsNew is true), Save() will use an INSERT query. After a successful save, the IsNew flag is set to false and the State property of the Fields object of the saved entity is set to EntityState.Fetched (if the entity is also refetched) or EntityState.OutOfSync.

Note:

Fields which get their values from a trigger, from newid() or a default constraint calling a user defined function are not considered sequenced fields and these values will not be read back, so you'll have to supply a value for these fields prior to saving the entity. This isn't true for fields which are of type unique_identifier on SqlServer 2005 when the DQE is set in SqlServer 2005 compatibility mode and the field has in the database a default value of NEWSEQUENTIALID(). See: Generated code - Database specific features

Note:

If the entity is in a hierarchy of type TargetPerEntityHierarchy (see Concepts - Entity inheritance and relational models) you don't have to set the discriminator value for the entity type, this is done for you automatically: just create a new instance of the entity type you want to use, and the discriminator value is automatically set and will be saved with the entity.

Modifying an entity

Modifying an entity's data is just as simple and can be done in multiple ways:

1. Loading an existing entity in memory, alter one or more fields (not sequenced fields) and call Save()
2. Create a new entity, set the primary key values, set the IsNew to false, set one or more other fields' values and call Save(). This will not alter the PK fields.
3. Via one of the UpdateMulti*() methods defined in the collection class of the entity.

Option 1 is likely the most used one, since an entity might already be in memory. As with all the suggested options, the Save() method will see that the entity isn't new, and will therefore use an UPDATE query to alter the entity's data in the persistent storage. An UPDATE query will only update the changed fields in an entity that is saved, which results in efficient queries. If no fields are changed, no update is performed. A field which is set to the same value (according to Equals()) is not marked as 'changed' (i.e. the field's IsChanged flag is not set).

If you've loaded an entity from the database into memory and you've changed one or more of its primary key fields, these fields will be updated in the database as well (except sequenced/identity columns). Changing PK fields is not recommended and changed PK fields are not propagated to related entities fetched in memory. You also can't save changed PK fields in recursive saves.

An example for code using the first method:


This will first load the Customer entity "CHOPS" into memory, alter one field, Phone, and then save that single field back into the persistent storage. Because the loading of "CHOPS" already set the primary key, we can just alter a field and call Save(). The Update query will solely set the table field related to the entity field "Phone".

Reading an entity into memory first can be somewhat inefficient, since all we need to do is an update of an entity row in the database.

Option 2 is more efficient in that it just starts an update, without first reading the data from the database. The following code performs the same update as the previous example code illustrating option 1. Even though the PK field is changed, it is not updated, because it is not previously fetched from the database.


We have to set the primary key field, so the Update method will only update a single entity, the "CHOPS" entity. Next, we have to mark the new, empty entity object as not being new, so Save() will call the Update method, instead of the Insert method. This is done by setting the flag IsNew to false. Next is the altering of a field, in this case "Phone", and the call of Save(). This will not load the entity back in memory, but because Save() is called, it will be marked out of sync, and the next time you'll access a property of this entity's object, it will be refetched from the persistent storage. Doing updates this way can be very efficient and you can use very complex update constructs when you apply an Expression to the field(s) to update. See for more information about Expression objects for fields Field expressions and aggregates.

Notes:

This will also work for fast deletes. If you want to set an identity primary key column, you'll notice you can't do that because it is marked as read-only. Use the method entityObject.Fields[fieldindex or fieldname].ForcedCurrentValueWrite(value). See the reference manual for details about this method (EntityField.ForcedCurrentValueWrite). Setting a field to the same value it already has will not set the field to a value (and will not mark the field as 'changed') unless the entity is new. Each entity which is saved is validated prior to the save action. This validation can be a no-op, if no validation code has been added by the developer, either through code added to the entity, or through a validator class. See Validation per field or per entity for more information about LLBLGen Pro's validation functionality. (SQLServer specific) If the entity is saved into a table which is part of an indexed view, SqlServer requires that SET ARITHABORT ON is specified prior to the actual save action. You can tell LLBLGen Pro to set that option, by calling the global method DbUtils.SetArithAbortFlag(bool) method. After each SQL statement a SET ARITHABORT OFF statement will be executed if the ArithAbort flag is set to true. Setting this flag affects the whole application.

For option 3, see Using the collection classes.

Setting the EntityState to Fetched automatically after a save

By design an entity which was successfully saved to the database gets as EntityState OutOfSync. The LLBLGen Pro runtime framework will refetch an entity which is marked OutOfSync automatically right before an entity field's property is read. This is done to make sure that default constraints, calculated fields and elements which could have been changed after the save action inside the database (for example because a database trigger ran after the save action) are reflected in the entity after the save action. If you know that this won't happen in your application, you can get a performance gain by specifying that LLBLGen Pro should mark a successfully saved entity as Fetched instead of OutOfSync. In this situation, LLBLGen Pro won't perform a fetch action to obtain the new entity values from the database.

To use this feature, you've to set the static/Shared property EntityBase.MarkSavedEntitiesAsFetched to true (default is false). This will be used for all entities in your application, so if you have some entities which have to be fetched after the update (for example because they have a timestamp field), you should keep the default, false. You can also set this value using the config file of your application by adding the following line to the appSettings section of your application's config file:

<add key="markSavedEntitiesAsFetched" value="true"/>

You don't need to refetch an entity if it has a sequenced primary key (Identity or sequence), as these values are read back directly with the insert statement.

Saving entities recursively

All entity objects and entity collection objects in SelfServicing support recursive saves. This means that if you have an entity object, say a CustomerEntity, and its collection objects, for example customer.Orders, contain changed entities, or the entity references changed entities, these entities will be saved as well when the particular entity is saved. In SelfServicing, this logic is not enabled by default, to be backwards compatible. You have to call the Save() (entities) or SaveMulti() (entity collections) overloads which accept a boolean parameter to signal the routine to save all entities recursively or not. Pass true to the Save / SaveMulti call and the whole object graph is saved, that is: all entities reachable from the object the Save (or SaveMulti) method is called on which are changed ('dirty').

All recursive save actions are performed inside a transaction. If the saved entity (the entity the Save() method is called on) or the saved entity collection is not participating in a transaction, a new transaction is created (ADO.NET transaction, not COM+). If there is already a transaction available, it is assumed all entities to save participate already in this transaction or can participate in this transaction (i.e. are not participating in another transaction). If an error occurs during the recursive save, the current transaction is aborted and the transaction is rolled back.

The logic automatically determines the order in which actions need to take place so foreign key violations do not occur.

For example:

• Instantiate a Customer entity, add a new Order object to its Orders collection. Now add OrderDetails objects to the new Order object's OrderDetails collection,. You can simply save the Customer entity and all included new/'dirty' entities will be saved and any PK-FK relations will be updated/synchronized automatically.
• Alter the Customer object in the example above, and save the Order object. The Customer object is saved first, then the Order and then the OrderDetails objects with all PK-FK values being synchronized

FK-PK synchronization
This synchronization of FK-PK values is already done at the moment you set a property to a reference of an entity object, for example myOrder.Customer = myCustomer, if the entity (in this case myCustomer) is not new, or if the PK field(s) aren't sequenced fields when the entity is new. Synchronization is also performed after a save action, so identity/sequenced columns are also synchronized.

If you set a foreign key field (for example Order.CustomerID) to a new value, the referenced entity by the foreign key (relation) the field is part of will be dereferenced and the field mapped onto that relation is set to null (C#) or Nothing (VB.NET). Example:


After line 'A', myOrder.CustomerID will be set to "CHOPS", because of the synchronization between the PK of Customer and the FK of Order. At line 'B', the foreign key field CustomerID of Order is changed to a new value, "BLONP". Because the FK field changes, the referenced entity through that FK field, Customer, is dereferenced and myOrder.Customer will return null. Due to lazy loading code and because there is no current referenced customer entity, the variable referencedCustomer will be set to a new Customer entity, fetched from the database with the PK "BLONP" at line 'C'.

The opposite is also true: if you set the property which represents a related entity to null (Nothing), the FK field(s) forming this relation will be set to null as well, as shown in the following example:


At line A, lazy loading will fetch the customer related to order 10254. At line B, this customer is dereferenced. This means that the FK field of order creating this relation, myOrder.CustomerId, will be set to null (Nothing). So if myOrder is saved after this, NULL will be saved in the field Order.CustomerId

Deleting an entity

Deleting an entity is very easy, it's as simple as Saving an entity. Simply fetch the entity into memory and call Delete(). You can also delete an entity using an entity collection or remove it from the persistent storage directly (both methods use DeleteMulti* overloads, see Deleting one or more entities from the persistent storage) To delete it the simple way: fetch it and call delete:


It's wise to add the entity object to a transaction object if you want to be able to roll back the delete later on in your routine. See for more information about transactions the section about Transactions.

Polymorphic fetches

Already mentioned early in this section is the phenomenon called 'Polymorphic fetches'. Imagine the following entity setup: BoardMember entity has a relation (m:1) with CompanyCar. CompanyCar is the root of a TargetPerEntityHierarchy inheritance hierarchy and has two subtypes: FamilyCar and SportsCar. Because BoardMember has the relation with CompanyCar, a field called 'CompanyCar' is created in the BoardMember entity which is mapped onto the m:1 relation BoardMember - CompanyCar.

In the database, several BoardMember instances have been stored, as well as several different CompanyCar instances, of type FamilyCar or SportsCar. Using lazy loading, you can load the related CompanyCar instance of a given BoardMember's instance by simply calling the 'CompanyCar' property:


However, 'car' in the example above, can be of a different type. If for example the BoardMember instance in myBoardMember has a FamilyCar as company car set, 'car' is of type FamilyCar. Because the fetch action can result in multiple types, the fetch is called polymorphic. So, in our example, if 'car' is of type FamilyCar, the following code would also be correct:


Would this BoardMember instance have a SportsCar set as company car, this code would fail at runtime with a specified cast not valid exception.

FetchPolymorphic

Each entity which is in an inheritance hierarchy has a method called FetchPolymorphic, which is a static/Shared method. This method lets you fetch an entity which is a subtype of the entity you call the method on. For example, if CompanyCar with ID '4' is a FamilyCar, you can do the following to fetch the entity into a FamilyCar instance:


As this method accepts a transaction, it can be handy in some cases to use this method over a constructor call. To keep things simple, you should first look at the constructor method:

FetchPolymorphicUsingUC...

Another way to fetch an entity polymorphically is when it has a unique constraint and is in a hierarchy. You then can use the unique constraint's values to fetch an entity polymorphically similar to the FetchPolymorphic method for fetching an entity using the primary key. Say Employee has an unique constraint on 'Name'. To fetch an employee polymorphically, you can use the following code.

Note:

Be aware of the fact that polymorphic fetches of entities in a TargetPerEntity hierarchy (see Concepts - Entity inheritance and relational models.) use JOINs between the root entity's target and all subtype targets when the root type is specified for the fetch. This can have an inpact on performance.

Concurrency control

There is an overloaded Save() variant which takes a predicate object, also known as a filter. This is also the case for Delete(). This filter is constructed using the objects described in Getting started with filtering and can be used to set a condition when the update (or delete, when the filter is used as a parameter to Delete()) has to take place (the filter is ignored when the entity is new). For example, a predicate object that contains a field = value compare clause for a timestamp column in the table where the entity-to-update is located. If the entity's timestamp column is not the same (if you have defined that in your predicate object passed to Save()), the save is not performed, or in the case of calling Delete() with a predicate, the delete will not take place.

To filter on the original database values fetched into the entity to be saved, you can create for example FieldCompareValuePredicate instances which use the EntityField's DbValue property. Even though a field is changed in memory through code, the DbValue property of a field will have the original value read from the database. You can use this for optimistic concurrency schemes. See for an example the example below. If the field is NULL in the database, DbValue is null (C#) or Nothing (VB.NET).

LLBLGen Pro supports another form of supplying predicates for filters during Save or Delete actions: implementing IConcurrencyPredicateFactory. You can implement this interface to produce, based on the type of action (save or delete) and the entity the predicate is for, an IPredicateExpression object which is then used as the filter for the action (Save or Delete). Each entity object has a property, ConcurrencyPredicateFactoryToUse, which can be set to an instance of IConcurrencyPredicateFactory. If specified, each Save() and Delete() call on the entity will consult this object for a filter object. This is also the case for recursive saves. If you want concurrency control deep down a recursive save, it's key that you set those object's ConcurrencyPredicateFactoryToUse property to an instance of IConcurrencyPredicateFactory. IConcurrencyPredicateFactory instances can't be shared between Adapter and SelfServicing code.

Below an example implementation of IConcurrencyPredicateFactory, which returns predicates which test for equality on EmployeeID for the particular order. This will make sure the Save or Delete action will only succeed if the entity in the database has the same value for EmployeeID as the in-memory entity.

Note:

In the VB.NET code above, operator overloading is used. If you're using VB.NET on .NET 1.0 or .NET 1.1, you don't have operator overloading functionality available as VB.NET for .NET 1.x doesn't support operator overloading, it was introduced in VB.NET on .NET 2.0. In the case that you're using .NET 1.x and VB.NET, create the predicates using: New FieldCompareValuePredicate(OrderFields.EmployeeID, ComparisonOperator.Equals, order.Fields(CInt(OrderFieldIndex.EmployeeID)).DbValue)

During recursive saves, if a save action fails, which can be caused by a ConcurrencyPredicateFactory produced predicate, thus if no rows are affected by the save action, an ORMConcurrencyException is thrown by the save logic, which will terminate any transaction started by the recursive save.

To set an IConcurrencyPredicateFactory object when an entity is created or initialized, please see the section Adding your own code to the generated classes which discusses various ways to modify the generated code to add your own initialization code which for example sets the IConcurrencyPredicateFactory instance for a particular object. You can also set an IConcurrencyPredicateFactory instance of an entity using the ConcurrencyPredicateFactoryToUse property of an EntityCollection to automatically set the ConcurrencyPredicateFactoryToUse property of an entity when it's added to the particular entity collection.

Entities, NULL values and defaults

Some datatypes, like date related datatypes and strings, are not always mandatory and are set to an unknown value. In most cases this is NULL: the fields in the table are nullable and, if these fields do not yet have a value, they're set to NULL. Nullable fields often have a 'default' value set; this is a value which is inserted by the database server when a NULL is inserted in such a column. These default values are defined in the table definition itself.

.NET 1.x: no support for nullable value types
In .NET 1.x, NULL values aren't usable inside .NET since a valuetype, for example a field of type int/Integer, which can be NULL in the database can't be null/Nothing in .NET 1.x. If you generate code for .NET 1.x or CF.NET 1.0, LLBLGen Pro's generated code converts all NULL values for all fields which have a ValueType as .NET type to default values for that particular ValueType. These values are defined in the Helper class 'TypeDefaultValue'. You can change these default values in the TypeDefaultValue class to other values, however keep in mind that these default values are not used most of the time: you always have to test for NULL for a given field, if it was NULL when the data was fetched from the database. To test a given field if it was NULL when you read it from the database, use TestOriginalFieldValueForNull():


The variable 'contactTitleIsNull' now contains true or false, depending on the fact if the field 'ContactTitle' for the entity "CHOPS" is NULL in the database (true) or not (false). This function will return true even if you've set the field to a new value but you have't saved the entity yet.

.NET 2.0: support for Nullable(Of valueType) types
In .NET 2.0, Microsoft introduced the concept of Nullable valuetypes, which means that a field of type int/Integer or any other ValueType can be null / Nothing. By default, LLBLGen Pro generates all ValueTyped fields as Nullable(Of valueType) if the target platform is .NET 2.0 or CF.NET 2.0. You can overrule this setting on a per-field basis by setting the preference (and project property) GenerateNullableFieldsAsNullableTypes to true or false, which controls the value of the setting for each field if the field has to be generated as nullable or not. (See: Designer - Adding and editing entities). With Nullable types for valuetyped fields, LLBLGen Pro won't convert a null / Nothing value for a field to a default value, but will return null / Nothing from the field's property.

NULL values read from the database
In previous versions of LLBLGen Pro, a NULL value read from the database would result in the default value for the field's type as the in-memory value. This has changed in V2 of LLBLGen Pro: if a field is NULL in the database, the in-memory value will then become null / Nothing. This means that the CurrentValue property of the field object in the entity's Fields collection (entity.Fields[index].CurrentValue) will be null / Nothing in this situation, not a default value.

Note:

Reading a value from an entity's field property (e.g. myCustomer.CompanyName), and the entity field hasn't been set to a value (which is the case in a new entity where the field hasn't been set to a value), an ORMInvalidFieldReadException is thrown, if the developer has set the static flag EntityBase(2).MakeInvalidFieldReadsFatal to true (default: false). In v1 you could get away with this and use the default value returned, but this isn't allowed anymore because nullable fields lead to different results now and that would otherwise go unnoticed when you upgrade your project, if the exception isn't thrown. Use the flag and the exception to track down code errors after migrating your v1 solution to v2.

Setting a field to NULL
Setting a field to NULL is easy. When you create a new entity, you simply do not supply a value for a field you want to set to NULL. The insert query will notice that the field isn't changed (because you didn't supply a value for it), and will skip the field. If you have set a default value for that column, the database engine will automatically fill in the default value for that field in the database, this is standard database behaviour. When you want to set a field of an existing entity to NULL, you have to use a special function: SetNewFieldValue(). You can set the field's value to null/Nothing and when you then save the entity, the value in the table will be NULL. You have to use this method and not a set operation on a property, because value types like int/Integer do not accept null/Nothing as a valid value. Using this method will not bypass checks, it's the same method that is used by properties to set the value for the fields related to the property. Example:


On .NET 2.0, with nullable types, this is even easier:


Usually, you won't be needing this much: most of the time fields will be set to NULL when the entity is created and will be updated with a value somewhere during the entity's lifecycle.

To test if a field is currently representing a NULL value, or better: if the entity would be saved now, does the field become NULL in the database, you can use a different method: TestCurrentFieldValueForNull():

Note:

The usage of NULLs in databases should be discouraged and NULLs should only be used for fields which are optional and often not filled in with a value. In other situations, always use a default value for a NULLable column.

Extending an entity by intercepting activity calls

During the entity's lifecycle and the actions in which the entity participates, various methods of the entity are called, and which might be a good candidate for your own logic to be called as well, for example when the entity is initialized you might want to do your own initialization as well. The entity classes offer a variety of methods for you to override so you can make your code to be called in various situations. These methods start all with On and can be found in the LLBLGen Pro reference manual in the class EntityBase. The entity classes also offer events for some situations, like the Initializing and Initialized events.

If you want to perform a given action when one of these methods are called, you can override them in the generated entity classes, preferably using the methods discussed in Adding your own code to the generated classes.

Note:

OnTransactionCommit and OnTransactionRollback are called on any entity participating in the transaction, no matter if there was an action on the entity or not. To check if an entity was saved during a transaction, test the entity's Fields.State property. If it's OutOfSync, the entity was saved.

IDataErrorInfo implementation

The .NET interface IDataErrorInfo is now implemented on EntityBase. Two methods have been added to the entities: SetEntityError and SetEntityFieldError, which allows external code to set the error of a field and/or entity. If append is set to true with SetEntityFieldError, the error message is appended to an existing message for that field using a semi-colon as separator.

Entity field validation, which is triggered by the entity's method SetNewFieldValue() (which is called by a property setter), sets the field error if an exception occurs or when the custom field validator fails. The error message is appended to an existing message.